Repository navigation
Declarative JSON mechanism files as the default interface - #17
Conversation
…#16) A mechanism may now be a JSON file (format "incept1d-mechanism/1"), compiled into the interface the solver uses; load_mechanism dispatches on .json. Step 1 of #16: everything the Paschen mechanism needs. * incept1d.expressions: rate coefficients, mobilities and yields are formulas. The string is parsed with ast and every node checked against a whitelist (numbers, names, + - * / **, exp/log/log10/sqrt/abs/tanh/ min/max) before the checked tree is compiled; literals are NumPy floats, so 1/0 and overflow give inf instead of raising or hanging. * incept1d.declarative: parameters, gas composition, definitions, species with charge and mobility, explicit alpha / eta (never derived from the reactions: an ionization that runs through a cascade has no single reaction to derive it from), reactions with k in SI times the densities of the neutral reactants the string names, and ion-induced yields per cation. Row selectors, drift directions and the reaction matrix follow from the file. Every key, name, reaction and charge balance is checked when the file is loaded. A configuration sets parameters by name, scales reactions by their string, and overrides parameters per polarity ('positive' / 'negative'); unknown keys are errors. * mechanisms/paschen/paschen.json: the Townsend model. Its augmented matrix equals paschen.py's to round-off (bit-identical on the tested grid) and incept1d pdiv gives identical curves for all three gases. paschen.py stays until the air mechanisms are converted too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…cheshnyi air (#16) Step 2 of #16: what the Pancheshnyi air mechanism needs, and the mechanism itself as mechanisms/air/pancheshnyi/air_pancheshnyi.json. * incept1d.tables: BOLSIG+ output (section-1 columns by label, A1/A2/...; section-2 rates by 'target type', summed over every process of that kind; the recorded mixture and gas temperature) and two-column LXCat tables. Each column is a variable of the mechanism, interpolated in E/N and held at the ends, as before. * incept1d.zheleznyak: the Zheleznyak absorption function and its two-stream fit, moved from mechanisms/air/zheleznyak.py (which keeps the command-line plot and re-exports them), with the fit cached per group count; a load is now 0.03 s instead of 0.2 s. * incept1d.declarative: - String parameters are files: relative to the mechanism file, or for a configuration value to the configuration first, as cross_sections was. - A BOLSIG+ table that records its mixture must match 'gas' to 1e-3; one that does not warns once unless the configuration sets the mixture; a run temperature more than 20 K from the table's warns once. - 'photoionization': absorption by a named model (zheleznyak, groups, absorber gas), source = named reactions times an efficiency formula, coupling per product species, cathode yield, optional direction (gives PHOTON_DIRECTIONS). The source uses the reactions' rates before multipliers, as air_pancheshnyi.py did. - cos, sin and pi in formulas. * air_pancheshnyi.json: A_aug equal to air_pancheshnyi.py's to <= 5e-15 for every shipped configuration and both polarities, alpha/eta/yields to round-off, and the test_air A3 reference values from the JSON mechanism. * conservative.json, databases.json: the five configurations whose tables (phelps, trinity, biagi) record no mixture now set the N2 0.8 / O2 0.2 that air_pancheshnyi.py used for them silently, so their results are unchanged and the assumption is visible. The JSON default is the 79/21 that lisbon.txt records. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Docs (Configuration chapter): * configuration/mechanisms.rst (new, Chap:MechanismFiles): the mechanism file block by block -- structure, formulas and the names they may use, parameters, gas, tables, definitions, species, Townsend coefficients, reactions and the rate convention, photoionization, emission -- what is checked at load, and when to write a Python mechanism instead. Its complete example is loaded by tests/test_docs.py. * overview, jsonfiles (configurations: parameters by name, multipliers, per-polarity overrides of any parameter, file resolution) and reactions rewritten with the mechanism file first; mechanismfile and configpy become the Python route, and configpy keeps the load_mechanism walk-through the overview had. * examples/paschen.rst and examples/air.rst include the mechanism files; the air page's configuration table follows the JSON parameters (and its eref default is corrected to 1.7e8 V/m, the value the code always used). * Every command in the docs, READMEs, figures Makefile and CLI help names the .json mechanisms, except incept1d chombo, which still reads only Python mechanisms. Paschen: paschen.py and its config.py are removed; gases.json sets A, B and gamma0 per gas; the tests and examples/paschen/closed_form.py write the closed form out themselves (identical table, solver to 1e-9 as before). The layout tests accept a directory holding a mechanism file, a Python mechanism, or both forms of one mechanism; a configuration with no label is "Baseline", as for the Python air mechanisms; two reactions with the same string are refused. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
generate_declarative tabulates a mechanism file in the layout generate writes for a Python mechanism: the rate coefficients as the file gives them, times the configuration's multipliers; alpha/N and eta/N from the file's alpha and eta (not summed from the reactions); the mean energy from its variable mean_energy. A file without alpha, eta or mean_energy is refused rather than given an invented column. Units follow the number of neutral partners (s^-1, m^3/s, m^6/s), which also corrects the Python path's m^6/s for 'X + M' and m^3/s for a unimolecular reaction in the mechanism-file table. For a .json mechanism the CLI reads the configuration with read_json_configs / load_mechanism, as every other command does, and the header names the file parameters. DeclarativeMechanism gains a small read-only interface for this (reaction_strings, mole_fractions, files, neutral_partners, rate_coefficient, neutral_density_factor, variable). The Phelps table from air_pancheshnyi.json equals the Python export in all 24 columns to <= 6e-16, with a reaction multiplier applied (K5-K7). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mechanisms/air/2body/air_2body.json: the two-body air scheme, with the quasi-steady-state ratios as definitions and the disabled O3- detachment kept as a rate of 0 with its candidate formula in a comment. Its A_aug, alpha, eta and yields equal air_2body.py's to <= 5.1e-16 for every configuration of example_config.json and both polarities. The reaction 'O2- + O2 -> e + 2O2', whose rate used the total density, is now written 'O2- + M -> e + O2 + M', so the string says what the rate does; its multiplier key in example_config.json follows. With incept1d chombo reading mechanism files, nothing needs the Python air code any more: air_pancheshnyi.py, air_2body.py, their config.py files, air_config.py and bolsig_conditions.py are removed (the mixture and temperature checks live in incept1d.declarative; their tests move to test_declarative D15-D15c). mechanisms/air/zheleznyak.py remains as the plotting command for the documentation figure. Tests: the air fixture, test_air, the layout and chombo tests use the mechanism files; the Python chombo path is tested on a minimal module written by the test. The equivalence checks against the deleted Python mechanisms ran before the deletion and are in the earlier commits' notes; what stays is the solver against closed forms and the reference values. Docs and comments that pointed to the Python air module for the coordinate convention now point to the Python interface page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@claude review |
|
Claude finished @rmrsk's task in 57s —— View job Review of PR #17: declarative JSON mechanism filesI read The design is clean. The expression whitelist is tight: Worth deciding before merge
Smaller points
Docs and housekeeping
Overall: the approach is sound, the equivalence evidence is convincing, and the strictness is a real improvement. Items 1 and 2 are the ones where behavior could silently differ from what a user expects. |
* expressions: function arity is checked when a formula is compiled
(exp/log/... one argument, min/max two), so exp(1, 2) is refused at
load with its place in the file instead of failing at the first call.
* declarative:
- Mole fractions must sum to 1 within 1e-9; the 1e-3 tolerance is only
for matching a table's recorded mixture.
- get_gamma_plus_with raises if given yields: a mechanism file's yields
come from its parameters and resolve(), and are never silently
ignored.
- resolve() passes the configuration's reaction multipliers through the
configuration, so the resolved object checks and holds them itself.
- _env documents its one-slot cache as not thread-safe.
* tables: a BOLSIG+ section with fewer columns than its header names, no
rows, or ragged rows is a TableError naming the file, not an IndexError.
* mechanism: Mechanism.init_photoionization, which nothing calls any more,
is removed, with its row in the Python interface table; the
transport-helper row now names only ElectronMeanEnergy, the one
incept1d chombo reads.
* Docs: the formula rules state the argument counts, that 0/0 is NaN and
warned about, and the sum tolerance.
* Tests D22-D27, including one that pins the photon source to the rates
before multipliers (documented, and what the Python air mechanism did).
Not changed, with reasons in the PR: NaN warnings stay (each is shown once
per location, and E/N = 0 gives NaN as it did before); no warning when E/N
leaves a table (clamping is documented and every root scan leaves the
range); the warning registry is cleared by the tests that need it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks for the review. Addressed in 819727d:
REUSE: the CI job "REUSE compliance" passes, and All 729 tests pass locally (including slow); pre-commit is clean apart from that 🤖 Generated with Claude Code |
|
Claude finished @rmrsk's task in 28s —— View job Re-review of 819727dI read the diff of 819727d against my earlier findings. I did not run the tests or pre-commit, so "verified" below means read in the diff, not executed.
New findingsNone block the merge.
Everything else in 819727d reads as intended. I found no new problems in the arity check, |
* tables: _rows takes the path, so ragged rows and a non-numeric token in a data row are TableErrors naming the file and the line, like a short or empty section (the previous commit claimed this for all of them; it held for two). D27 now covers all four faults. * test_paschen_mechanism: a 'negative'-only gamma0 override goes through the full solver in both polarities, each matching Paschen's law with its own gamma -- the end-to-end polarity check that the comparison with the old Python Paschen module used to provide. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Re-review points, addressed in f6b6e04:
734 tests pass locally. 🤖 Generated with Claude Code |
Summary
Closes #16. A mechanism is now a JSON mechanism file, checked strictly when it is loaded and compiled into the interface the solver already uses; it is the documented, default way to describe a gas. Paschen, Pancheshnyi air and two-body air are converted and their Python code removed. Python mechanisms remain the opt-in route for models the format cannot express (RFD).
Background
A mechanism was a Python module exposing the solver's own matrices (
get_R,get_B, the row selectorsΠ, ...), plus aconfig.pythat injected globals before the module ran. Every derivable input was built by hand, configuration keys were checked inconsistently (Paschen'sconfig.pydropped unknown keys silently), a fallback gas mixture was applied silently, and loading someone else's mechanism meant running their code. The Pancheshnyi air scheme took 1555 lines across module, config and shared helpers.Solution
incept1d.expressions— Coefficients are formulas. The string is parsed withast, every node checked against a whitelist (numbers, names,+ - * / **,exp log log10 sqrt abs tanh cos sin min max), and only the checked tree is compiled. No attributes, subscripts, comparisons, conditionals or other calls. Literals are NumPy floats, so1/0and overflow giveinfinstead of raising or hanging.incept1d.declarative— The format ("format": "incept1d-mechanism/1"):parameters,gas,tables,definitions,species(charge, mobility), explicitalpha/eta,reactions(k in SI times the neutral densities the string names),photoionization(absorption model, source reactions × efficiency, coupling per product, cathode yield, optional direction →PHOTON_DIRECTIONS),emission. Row selectors, drift directions and the matrices follow from the file. Load-time checks: unknown keys, unknown or reused names, charge balance, one tracked reactant, declared products, duplicate reactions, mixture in [0,1] summing to 1, a yield for every cation.parameters(numbers, or file names resolved against the configuration first),label,reaction_multipliers(keyed by reaction string; unknown keys refused) andpositive/negative(any parameter, per polarity). Anything else is an error.incept1d.tables— BOLSIG+ output (transport columns by label, rates by'target type'summed over processes, recorded mixture and temperature) and two-column LXCat tables. A table that records its mixture must matchgasto 1e-3; one that does not warns unless the configuration sets it; a run temperature > 20 K from the table's warns.incept1d.zheleznyak— The two-stream Zheleznyak fit moved into the package and cached per group count (load 0.03 s instead of 0.2 s).mechanisms/air/zheleznyak.pystays as the figure's plotting command.incept1d chombo— Exports mechanism files: the file's rate coefficients with multipliers, alpha/N and eta/N from itsalpha/eta, the mean energy from itsmean_energyvariable (refused if absent).paschen.json(36 lines),air_pancheshnyi.json(96),air_2body.json.configuration/mechanisms.rst(the format, block by block, with the rate and photon equations; its complete example is loaded bytests/test_docs.py); overview, configuration files and modifying reactions rewritten with mechanism files first; the Python pages framed as the advanced route; the Paschen and air example pages include the files. Every command in the docs, READMEs, figure Makefile and CLI help names the.jsonmechanisms.Design decisions (from the issue discussion)
alpha/etaexplicit, never derived from the reactions — a model may ionize through a cascade (e + M -> e(low) + e(low) + M+,e(low) -> e) with no single reaction to derive α from; derivation would silently give 0.Evidence
Equivalence with the Python mechanisms, checked before each was removed:
incept1d pdivoutput (3 gases × 30 pd)test_airA3 inception fields 175.4867 / 116.2765 / 100.711 Tdexample_config.jsonconfig × both polaritiesWhat stays in the suite: Paschen against its closed form (1e-9), the air reference values, strict-loading tests (
tests/test_declarative.py), the documented example, and the chombo columns against the mechanism's own R.Side-effects
databases.jsonandconservative.jsonsetx_n2 = 0.8, x_o2 = 0.2for Phelps/Trinity/Biagi, which record no mixture — whatair_pancheshnyi.pyused for them silently; results unchanged. The default is the 79/21 thatlisbon.txtrecords.O2- + O2 -> e + 2O2→O2- + M -> e + O2 + M(its rate always used the total density); the multiplier key inexample_config.jsonfollows.X + Mand m³/s for unimolecular reactions do not occur for mechanism files.eref= 1.7e9 V/m; the code always used 1.7e8.Mechanism.init_photoionizationremoved. The wrapper had no callers; a Python mechanism's ownconfig.pycan still call its module's function inpost_exec_init.Alternative solutions
ionization/--streamer-criterion.PR-review checklist
Mandatory:
pre-commit run --all-files(black, flake8, Sphinx) and it passed. All hooks pass;reuse lintfails locally only on an untracked.claude/checkout that is not part of the repository.make -C docs htmlbuilds without warnings. Dummy builder with-W; default figures rebuilt.@claude review. Findings addressed in 819727d; see the reply in the thread.If this PR changes the physics or the numerics:
docs/source/theory/in the commit message or docstring, and updated the theory page if the model itself changed. No model change; the reference citeseq_two_stream,eq_two_stream_directional.mechanisms/air/pancheshnyi/paschen.jsonand it still reproduces the standard Paschen law.test_airA2, slow suite.If this PR adds or modifies a mechanism:
_comments and the air docs.paschen.json(air),gases.json(Paschen).🤖 Generated with Claude Code